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AES Changes 


AES Version Number; The AES version number returned in glObl[0] after appijnit is 

now 0x0300 (version 3.0). 


Critical Error Handler: No context switching will happen in the AES rririr^l error 

handler. Previously, this could have caused recursive 
GEMDOS calls if a timer event was waiting at the time a 
critical error happened. Now all processes are blocked until 
the user dismisses the critical error alert box. Remember that 
GEM programs which take the critical error handler must not 
make any AES or GEMDOS calls while handling a critical 
error. No GEMDOS calls because GEMDOS is not recursive at 
all, and it could have been a GEMDOS call which triggered 
the critical error. No AES calls because an appEcation makin g 
an AES call will cause a context switch, and the AES process 
switched to might make a GEMDOS call. 


Desk Accessories: On startup and after a change of resolution, the AES now 

creates a GEMDOS process for the code that starts up d e s k 
accessories and launches the desktop. As a result, «//memoiy 
which is allocated by accessories and the Desktop will be 
freed on a resolution change. Previously, it was possible for a 
desk accessory to Malloc memory which did not get freed 
because the AES had no way of knowing about that memory. 
Now, the Desktop (as a GEMDOS process) actually terminates 
on a resolution change, and GEMDOS frees all the memory 
allocated to it. 
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Any appLexit call will now block the calling process until all 
desk accessories are waiting for a message event. As a result, 
under this AES version, DAs can safely MallOC memory. 
Memoiy allocated by a DA is actually owned by the GEMDOS 
process that is running when the application makes the Malloc 
call. When that process terminates, GEMDOS will free the 
memoiy. Previously, the AES was not always getting 
AC_CL0SE messages to DAs until after a program had already 
terminated, and all of its resources freed. Now, a DA can be 
assured that it will receive the AC_CL0SE message b^ow the 
application terminates, so any memory that it has allocated 
will not already be invalidated at AC_CL0SE time. 

This improved AC_CL0SE handling helps with VDI 
workstations opened by desk accessories as well. When a 
workstaticn is opened, the VDI makes a GEMDOS MallOC call 
to allocate memoiy for an application's workstation. 

Previously, any workstation opened by a desk accessory 
would be freed when its parent application terminated, and 
possibly before the DA got its AC_CL0SE message and was 
able to dose the workstation. 


Menu/Alert 

Screen Buffer: The menu/alert screen buffer is now 1/2 the size of the screen 

memory. 


Mouse, Keyboard, and 

Screen Ownership: Mouse, keyboard, and saeen control ownership are now 

unconditionally changed to the previous process after a 
process is run by the shell library. This shouldn't affect any 
applications except the Desktop, but it does make error 
recovery from errant programs more reliable. 
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Window Colors 


Two new wind_set calls are provided in the Atari GEM AES version 3.0 to set the colors of 
window elements. See the GEM AES manual section 11.3.6, page 11-21 for information 
on the wind_set call. The parameters for setting window element colors are as follows: 

wind_set( WORD handle, WORD field, WORD element, WORD tcolor, WORD bcolor ); 

The "field" values for these new calls are 18 (WF_C0L0R), to set window element colors by 
window handle, and 19 (WF_DC0L0R), to set default window element colors. When using 
WF_C0L0R, handle is the AES handle of the window whose colors are to be set. When 
using WF_DC0L0R, the handle parameter is ignored. 

Applications should normally noi use WF_DC0L0R to set the default colors, because users 
will use the Window Colors control panel extension to set the default window colors they 
want to see. Instead, applications should use WF_C0L0R to set window colors for their 
own windows. 

The element parameter determines what part of the window (dose box, name, horizontal 
slider, etc.) is set by the caU. Window element numbers are defined in WCOLOR.H. These 
numbers should not be confused with the bits which define window parts for wind_create 
and wind_calc - they are different Also remember that not all elements are visible on aU 
windows. We could spend several pages describing what elements are visible under 
what crrcumstances, but the result would be more confusing than enlightenin g The l^est 
way to find out what elements are visible in a given window is to experiment with 
different color settings. 

The tcolor parameter defines the element color when the window is topped; bcolor defines 
the color when the window is in the background. A value of -1 for tcolor or bcolor means 
"don't change." 

Because AES windows consist of a group of normal AES objects, what you actually set 
with these calls is the "object color WORD" for the window element you are setting. 

Thus, you set not only the text, border, and fill colors fcx the window plem^nt but also 
the fill pattern and text mode (replace/transparent). See the GEM AES manual section 
6.37.4, page 6-l6 for more information on the object color WORD. WCOLOR.FI provides C 
macros for converting color indices into a nybble-packed color word. 
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Applications which use wind_S6t to set window element colors should allow users to 
choose color sets. It is recommended that an interface .similar to the Window Colots 
control panel extension be used for application based window color settings. As 
appropriate, prosride controls that allow the user to select colors for elements or groups of 
elements which will be visible in the application's windows. Also provide reasonable 
default color sets which use the standard GEM palette. Keep in mind that a user may- 
have set up a custom palette that renders your default color sets ugly or unusable. 


Pages 
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WCOLOR.H 


rWCOLOR.H 

* definitions for new wind_set call WF_COLOR and WF_DCOLOR 

* 900614 kbad 
7 

Idefine Color2Border( c ) ( (c) « 1 2 ) 

#defineColor2Text(c) ((c)«8) 

#defineColor2Fill(c) (c) 

fdefine ColorWord( borderColor, textColor, fillColor )\ 

( Color2Border(borderColor) I \ 

Color2Text(textColor) I \ 

Color2Fill(tillColor)) 

#define WF_COLOR 18 /* set element color words by handle 7 
#define WF_DCOLOR 19 /* set default element color words 7 

r 

New wind_set call for setting window element colors: 

wind_set( WORD wjd, WORD field, WORD element, WORD tcolor, WORD bcolor); 

field: WF_COLOR set object color words for window element by handle 
field: WF_DCOLOR set default object color words for window element 
(wJd parameter is ignored for WF_DCOLOR) 
element: part of window to set, defined below 
tcolor: object color word used when window is topped (-1: ignore) 
bcolor: object color word used when window is not topped (-1 : ignore) 


7 


/‘Window elements 



object type 

description 

fdefineW BOX 

0 

/* 

IBOX 

window parent object 

#defineW_TITLE 

1 

/* 

BOX 

parent of closer, name, fuller 

fdefineW CLOSER 

2 

/* 

BOXCHAR 

close box 

fdefineW NAME 

3 

/* 

BOXTEXr 

mover bar 

fdefineW_FULLER 

4 

/* 

BOXCHAR 

full box 

fdefineWJNFO 

5 

/* 

BOXTEXT 

info line 


7 

7 

7 

7 

7 

7 

7 
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#defineW DATA 

6 

r 

IBOX 

#defineW_WORK 

7 

r 

IBOX 

#defineW_SIZER 

8 

r 

BOXCHAR 

#defineW_VBAR 

9 

r 

BOX 

#defineW_UPARROW 

10 

r 

BOXCHAR 

#defineW_DNARROW 

11 

r 

BOXCHAR 

fdefineW VSLIDE 

12 

r 

BOX 

#defineW_VELEV 

13 

/* 

BOX 

#defineW_HBAR 

14 

r 

BOX 

fdefineW LFARROW 

15 

r 

BOXCHAR 

#defineW_RTARROW 

16 

r 

BOXCHAR 

#defineW_HSLIDE 

17 

r 

BOX 

fdefineW HELEV 

18 

r 

BOX 


holds remaining window elements 7 


application work area 7 

sizer box 7 

holds vertical slider elements 7 

vert, slider up arrow 7 

vert, slider down arrow 7 

vert, slider background 7 

vert, slider thumb/elevator 7 

holds horizontal slider elements 7 

horz. slider left arrow 7 

horz. slider right arrow 7 

horz. slider background 7 

horz. slider thumb/elevator 7 
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GEMDOS, BIOS, and XB IOS Changes 

— Cookie: The _FPU cookie describes what hardware and software 

floating-point support is installed in the machine. The lew- 
word of the cookie's value describes software floating-point 
support; currently, this is always zero, but Atari may assign 
values in the future for software floating-point support 
packages. Notably, the 68040 requires software to support 
some of the instructions that the 68881/68882 execute on- 
chip. 

The high word describes the hardware floating-point installed 
in your system. Note that the "unsure" cases result because 
the BIOS probes for the 6888x without dete rmining which 
FPU you have. If some software cares, it can prebe, and reset 
the cookie's value accordingly. The BIOS always \nsX 3 S\s an 
_FPU cookie, even with zero value, so floating-pcint support 
software can change the low word when it installs itself. 


_FPU Cookie ChJ^ wotxl) 

Value Meanit^ 

0 No hardware FPU detected 

1 SFP004 or compatible: 68881 as peripheral 

2 68881 or 68882, unsure which, as coprocessor 

3 68881 or 68882 plus SFP004 

4 68881 for sure 

5 68881 plus SFP004 

6 68882 for sure 

7 68882 plus SFP004 

8 68040's internal floating-point support 

9 68040 plus SFP004 

Note: If your software requires floating point support, check 
this cookie for a non-zero value in either the high or 
low word. 
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Malloc: 


Sversion: 


TOS Version Numbers 


Malloc(0L) returns zero. It used to return a pointer, but since 
the call doesn't allocate any memory, the pointer painted to 
memory that nobody owned, and that pointer could not 
legally be used. Now a Malloc request for zero bytes is 
considered an error, and MallOC returns zero. 


Sversion returns the GEMDOS version number. The return 
value has the "major" revision number in the lowby\j& and the 
"major" revision number in the byte. 


Version 

Mr^or 

Mega TOS 1.02 

00 

Rainbow TOS 1.04 

00 

STE TOS 1.06 

00 

STE TOS 1.62 

00 

TT TOS 3.01 

00 


Minor 

Returned by 
Sversion 

13 

0x1300 

15 

0x1500 

15 

0x1500 

17 

0x1700 

19 

0x1900 


The TOS version number for the first release of TT TOS is 
TOS 3.01. 
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New GEMDOS Calls 


Mxalloc [68 / 0x44] Allocate memoiy 

(with preference) 


LONG Mxalloc(amount, mode) 
LONG amount; 

WORD mode: 


This call works like MallOcQ, but takes an extra parameter; a flag telling where to get the 
memory. 

Mode Meaning 

0 ST RAM only 

1 alternative RAM only 

2 either, ST RAM preferred 

3 either, alternative RAM preferred 

If amount is -IL, the size of the largest single block of the type specified by mode is 
returned. In that case, mode values 2 and 3 are identical, and the size of the largest block 
of either type is returned. 

If amount is not -IL, a block amount bytes long is allocated to the r ailin g process and a 
pointer to it is returned. If mode is 0 or 1 , the block will come from the kinH of memory 
specified. If mode is 2 or 3, the "preferred" type of memory is checked first for a laige- 
enough block, then the other type is checked. 

If alternate RAM is eligible to satisfy a request, but there isn't enough of it available, the 
request will come from ST RAM. If there isn't enough of that, the request fails. 

It should be dear that the MallOCQ call devolves into a MxallocQ call with a mode value of 0 
or 3, depending on the state of the Malloc-eligibility bit in the program's header. 
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Maddalt [20 / 0x14] Inform GEMDOS of 

"alternative" memory 

LONG Maddalt(start,size) 


This call causes GEMDOS to become aware of memory that it can use for loading 
processes and satisfying Malloc calls. It can be used to inform GEMDOS of memory that 
the BIOS memory-sizing algorithm did not tell GEMDOS about initially 

The arguments Start and siz6 must describe a contiguous block of memory, and once this 
call is made that memory "belongs" to GEMDOS. There is no way to "take it back," and 
no pregram should use this memory except through GEMDOS's MallOC and Pexec calls. 

The memory so added is "alternative" memory; that is, it is only eligible for program 
loading if the Alternative RAM Load bit is set in the header of the program being loaded, 
and it is only eligible for satisfying Malloc calls if the Alternative RAM Malloc is set, or if 
Mxalloc modes 1 or 3 is used. 

Maddalt returns 0 for success, or an error code for failure. 

This call should only be made once for a given block of memory. The best way to do 
this is to run a program in your AUTO folder that makes the Maddalt call. This would only 
be appropriate if there is memory in your system that you want to use for pregrams and 
Malloc calls, and which the BIOS doesn't "find" and tell GEMDOS about at boot timp 
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New XBIOS Graphics Calls for the TT030 


Warning: Use of these calls is restricted to the TT only. For compatibiHty with other 

Atari computers use of these calls should be limited to those applications 
which will require porting due to other incompatibility. 


EgetPalette [85 / 0x55] Get Look Up Table 

registers 


VOID EgetPalette(colorNum, count, paletteRr) 

WORD colorNum, count; 

LONG palettePtr; 


Copy the contents of a contiguous set of TT hardware color Locdc Up Table GLUT) 
registers starting with register COlorNum into the area pointed to by paletteRr. count words are 
transferred into the area. paletteRr must fall on a word boundary. 


EgetShift [81 / 0x51] Get current shift 

mode value 

WORD EgetShiftO 


Return the current shift mode register value. See Es^shift for details. 


Atari TW30 TOS Release Notes - 6 S^tember 1991 


Page 15 


EsetBank [82 / 0x52] 


Set color Look Up bank 


WORD EsetBank(bankNum) 

WORD bankNum; 


Set bank nuniber (0-15) for active TT color Look Up Table (LUI). This caU also maps the 
current bank's colors to the old ST color Look Up Table. The bank is set immediately. 
Function always returns old bankNum. If bankNum is negative, the hardware register is not 
altered. 


EsetColor [83 / 0x53] Set color entry 

WORD EsetColor(colorNum, color) 

WORD colorNum, color; 


Set the absolute entry colorNum in the TT color Look Up Table (LUT) to the given ccior. 
color is set immediately. Always returns the old color. If color is negative, the hardware 
register is not altered. 
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EsetGray [86 / 0x56] Set/clear gray mode 


WORD EsetGray(switch) 

WORD switch; 


Set the manner in which the color Look Up Table aUD data is interpreted by the display 
hardware. A switch value of zero directs the display hardware to interpret the LUT data as 
color, 4 bits for each cf the three components. With a non-zero switch value, the upper 
byte of the LUT entry is ignored and the lower byte alone represents one of 256 gray 
levels. Always returns the old switch value (a non-zero value means switch is set). On 
input if switch is set to a negative value, the hardware register is not altered. 


EsetPalette [84 / 0x54] Set palette registers 

VOID EsetPalette(colorNum, count, paletteRr) 

WORD colorNum, count; 

LONG palettePtr; 


Set the contents of a contiguous set of TT hardware palette registers with the words 
pointed to by paletteRr. paletteRr must fall on a word boundary. The set of registers loaded 
begins with Look Up Table auD register COlorNum and extends for count words. The 
function sets the palette immediately. 
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EsetShift [80 / 0x50] 


Set shift mode register 


WORD EsetShift(shftMode) 

WORD shftMode 

Set the IT shift mcxle register to ShftMode. Return old shift mode register value. 


Bit Assignments 

S--G-MMM--- 

-BBBB 

S = Smear Mode 
G = Gray-Mode 

MMM = Mode; 000 

320x200x4 

001 

640x200x2 

010 

640x400x1 

100 

640x480x4 

110 

1280x960x1 

111 

320x480x8 

BBBB = Bank 


For more information on Gray-Mode see: EsetGray. Note the values returned by GetrezO 
correspond to the Mode information given here. Also, it is easier to rhangp individual 
elements of this register using the specialized calls below. They should be used 
whenever possible. 
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EsetSmear [87 / 0x57] 


Set/clear video 
smear mode 


WORD EsetSmear(switch) 

WORD switch: 


Set the video smear mode. A Switch value of zero indicates no rmal display mode while a 
non-zero value instructs the display hardware to repeat (smear) the last non-zero color 
encountered whenever zero values are retrieved. Function always returns the old switch 
value (a non-zero value means switch is set). On input, if switch is set to a negative value, 
the hardware register is not altered. 
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New XBIOS Calls 


Bcomnap [44 / Qx2C] Change mapping 

of device 1 


LONG Bconmap(devno) 

WORD devno: 


This call maps devno in as Boon* device number 1. It returns the old ma pping If devno is - 
1, there's no change; the current mapping is simply returned. If devno is -2, a pointer is 
returned (see below). Legal values are -1 (for no change), -2 (to return the pointer), and 
values 6 and up. 

You can tell you're on a system which doesn't support Bconmap by makin g the call and 
checking the return: if the return value is 44 (0x2C, the same as the XBIOS call number) 
then Bconmap is not available. 

In addition to the above, if dovno is -2, a pointer to the device mapping structure is 
returned. This is used by pregrams which need to install new mappable handlers. It also 
contains the number of mappable devices; the highest legal devno value for Boon calls 
(including Bconmap itself) is that number plus 5. 

Illegal values (0-5, or higher than the highest legal value, or negative but not -1 or -2) 
don't change anything, and return 0. 

The mapping is accomplished by writing into the (published) veaor table in low mem ory. 
In addition, new pointers are used to make lorec and Rsconf indirea. Therefore, programs 
which use the veaor table in low RAM and/or lorec and Rsconf will see the "currently- 
mapped" device when they make Boon calls with devno=1 , and when they makp lorec and 
Rsconf calls. 
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Bconmap-aware programs can use the higher devno values to get at a specific port, no 
matter what the current mapping is. They still need to use Bconmap to "map in" the 
desired port before making lorec and Rsconf calls. 


DMAread. [42 / Qx2A] Read sectors from device 


LONG DMAread(sector, count, buffer, devno) 

LONG sector; 

WORD count: 

VOID ‘buffer; 

WORD devno: 


Read sectors from the device into memoiy. Works for ACSI and SCSI devices. For SCSI, it 
does not actually use DMA: it handshakes the bytes across. 

Device numbers are: 

devno Device 

$0-$7 ACSI devices $0-$7 

$8-$f SCSI devices $8-$f 

other reserved for future use 

Returns a BIOS error code. This call assumes the memory at buffer can actually be 
accessed by the bus the device is on. Therefore, DMAread from an ACSI device into 
alternative RAM won't work. 

For SCSI reads, DMAread will transfer data from the device until the device exits the data- 
transfer phase. This means it will read the number of seaors specified in the call, 
regardless of the seaorsize of the device. Some devices on the SCSI bus (notably CD 
ROM) may have sector sItes of 2K or laiger. Programmers should use an extra-large 
buffer when reading from unknown devices; 2K or 4K per seaor is recommended. 
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The TT uses DMAread internally to read the boa seaor of each DMA device. The buffer it 
uses (called diskbut and pcmted to by the system variable _diskbufp) is only guaranteed to 
be IK in size. It happens to be more than that at present, so a device with large sectors 
should not be a problem; however, some specific maximum will have to be settled upon 
in the future. The current thinking is to guarantee 4K, which is twice as much as the 
device with the largest seaors we're aware of (CD ROM). 


DMAwrite [Qx2B / 43] Write sectors to device 


LONG DMAwrite(sector, count, buffer, devno) 

LONG sector; 

WORD count; 

VOID ‘buffer; 

WORD devno; 


Write seaors from memory to a device. Works for ACSI and SCSI devices. For SCSI, it 
does not actually use DMA: it handshakes the bytes aaoss. 

Device numbers are: 

devno Device 

$0-$7 ACSI devices $0-$7 

$&-$f SCSI devices $8-$f 

other reserved for flimre use 

Returns a BIOS error code. This call assumes the memory at buffer can actually be 
accessed by the bus the device is on. 
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NVMaccess [46 / 0x2£] 


Access Non-Volatile 
Memory 


WORD NVMaccess(op, start, count, buffer) 

WORD op, start, count: 

BYTE ‘buffer; 


This call manages the non-volatile memory (NVM) in the TTs real-time dock chip. There 
are 50 bytes of memoiy there, of which two are reserved at the end as a check on the rest 
of the data. This call validates the check data on reads, recomputes the check data on 
writes, and initializes the check data if you want. 

Opcode Meaning 

0 READ: copy data from NVM to the buffer. 

1 WRITE: copy data from the buffer to NVM. 

2 INTT: zero the NVM and initialize the check data. 

Start specifies the first location to read or write; count specifies the number of bytes to 
transfer. 

Returns zero for success, EBADRQ (-5) for a range error in the arguments, and EGENRL (-12) 
if the NVM check data isn't consistent before a read or write. In the case of a read the 
data is transferred anyway. 

NVM usage is to be dictated by Atari. We will take suggestions and applications for 
assignments of bytes, but using bytes or values whose meanings are not published by us 
assures trouble in the future. 
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Bconmap Discussion 


BconmapO makes the new serial ports on a TT030 accessible to programs which were 
written when there was just one serial port 

There are new Bconin/oul/stal/ostat device numbers on a TT: 

devno Meaning 

0 PRN 

1 currently-mapped serial port (see below) 

2 CON 

3 MIDI 

4 IKBD 

5 EAW 

6 ST-compatible serial port (called Modem 1; default). 

7 see ChWiel B (Modem 2 on the back of a TD. 

8 TTMFP serial port G-wire, Serial 1). 

9 sec Channel A (full handshake, Serial 2). 

Bcon calls on device 1 (normally AUX) might actually refer to any of these devices, or to a 
user-installed device (with an even higher devno). You use Bconmap to rhangP the' 

mapping of device 1. Bconmap also changes the mapping of RsconfQ calls, and of lorec calls 
with lorec device number 0. 

The port assignments above are for TT only; other machines with "extra" pons will 
have other assignments. Port 6 is always going to be the ST-compatible one, though. 
Other devices may be installed by drivers at boot rim n (ca- even later). 
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Installing New Bconmap Device Drivers 


Bconmap(-2) returns a pointer to a structure. The structure looks like this: 

Struct bconmap { 

LONG *maptab; /* ptr to map table (see below) 7 

WORD maptabsize; /* number of lines in the table 7 

}; 

The map table contains a line for each device. Each line contains pointers to the Bconstat, 
Bconin, Bcostat, and Bconout routines, plus a pointer to the Rsconf routine, plus a painter to 
the lorec for that device. The table's size (the number of devices) is in maptabsize. Maptabsize 
is used by all Bcon calls to range-check the device number. The highest legal value for 
Bcon calls (including Bconmap) is this number plus 5. 

A Bconmappable driver must have Bconstat, Bconin, Bcostat, and Bconout entry points, plus an 
iorec, plus an Rsconf function pointer. You install it by copying the table pointed to by 
maptab into a larger area and adding your driver's entry (five procedure pointers and an 
iorec pointer), then changing maptab and maptabsize. 

In the unlikely event that your prc^ram finds itself installing the 38th device, that is, the 
one which would have Bconmap number 44 (decimal), you should actually allocate TWO 
new rows for maptab, install your device in the SECOND one, and increment maptabsize by 
two. Otherwise, a current mapping of device 44 would be indistinguishable ffcan the case 
where Bconmap was not available at all. No programs should be told to use device 
nun±>er 44. 
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Bconmap and Rsconf 


Rsconf has been mis-documented for some time. It actually returns a longword value. 

That longword is four bytes stuck together. Those four bytes are the UCR, RSR, and TSR 
registers of the MFP, plus a useless byte. The UCR register is in the high byte of the 
returned longword, foUowed by the RSR, then the TSR, and the useless byte in the low- 
order byte. These bytes are the values of those registers BEFORE the changes dictated by 
the arguments to Rsconf. 

In addition, ever since Rainbow TOS, Rsconf(-2,-1, -1,-1 ,-1,-1) returns the last baud-rate value 
set with Rsconf. If the first argument is -2, all the other arguments are ignored. 

In the wcffld of Bconmap, the Rsconf arguments have to be interpreted slightly differently. 
Nca every device is a 68901 MFP any more. For the new devices, the bits which makp 
sense are used, the others discarded. 


Prcgiammers should use Rsconf(-1 ,-1 ,-1 ,-1 ,-1 ,-1 ) to read the current values, then change the 
bits they want to change and call Rsconf again with the new values; changing bits in 
registers not listed below is now considered illegal. (Consider a REAL MFP: TSR contains, 
among other things, the transmitter enable bit; if you write 0x08 to cause a break, you will 
be disabling the transmitterl) 

The bits in the Rsconf args and return value which Bconmappable devices must emulate are 
as follows: 

UCR: bits 6-5: word-length (00=8, 01=7, 10=6, 11=5) 

bits 4-3: stop bits: (01=1, 10=1.5, 11=2; 00 is invalid) 
bit 2: parity (0=no, l=yes) 

bit 1: parity (0=odd, l=even, meaningful only if bit 2 is 1) 

RSR: none 

TSR: bit 3: break (sends break while 1) 

SCR: none 

Programs which use synchronous modes prciiably talk directly to their hardware, so it 
doesn't make much sense to "emulate" that here. If a legal value is inconvenient (such as 
1.5 stop bits with hardware which doesn't support it, or a baud rate you can't support) 
you can ignore it: users will get used to the restrictions imposed by your device and 
driver. 
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Serial 2 vs. LAN Connector 


see channel A is shared between the DB9 on the back of the TT030 Oabelled Serial 2) 
and the round LAN connector on the left side. Initially, it is pregrammed to use the DB9 
conneaor. The selection can be made as follows: 

Selea LAN conneaor: 0ffgibit(0x7f); /* clear bit 7 (only) 7 

Selea DB9 conneaor: 0ngibit(0x80); /* set bit 7 (only) 7 
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The Two Kinds of RAM 


This section discusses the concept of "alternative RAM" in general first, and gets to the 
specifics as they relate to the TT030 later. 

In the TTO 3 O and other ST-Uke machines planned for the future, there are two general 
kinds of RAM: there is ST RAM, which is ST-compatible, and there is "alternative RAM," 
which is not. Exactly how it is not varies by machine and type of RAM. Primarily, the 
video chip can only display screen data from ST RAM, and the DMA sound chip can only 
play data stored in ST RAM. Secondarily, other chips which access memory, like ACSI 
DMA (for ST hard disks and other devices) and SCSI DMA (for SCSI devices), may not be 
able to get at alternative memory directly. This affects most programs not at all, since they 
use BIOS and GEMDOS calls to accomplish this kind of transfer, and the device driver is 
responsible for getting the data from here to there transparently, no ma tter where "here" 
and "there" are. 

The "rules for eligibility" for a program running in alternate RAM are: 

(1) It must not try to set the screen base address in alternative RAM, or play DMA 
sound from there. 

(2) It must not try to make a device driver do DMA from or to there, unless the device 
driver knows about the differences between ST RAM and alternative RAM. 

0) It must ncrt try to do DMA itself from or to there (only specialized device drivers do 
this). 

The second point is a bit sticky: it refers to the fact that existing DMA device drivers don't 
know about the restrictions on alternative RAM. 

Since pregrams written before there was any concept of alternative RAM don't know if 
they break the rules or not, you, the user, must inform GEMDOS as to whether a program 
is eligible to use alternative RAM, or must use ST RAM. As a finer distinction, you can 
selea the eligibility for program loading and MallocQ calls separately. A pregram which 
MallOCs a screen buffer might still be eligible to load into alternative RAM, but its MaliOCQ 
calls must be satisfied from ST RAM. 
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The Specifics of the Two Kinds of RAM 


As of Rainbow TOS , one of the reserved longwords in the header of executable files 
(PEG, TIP, TOS) acquired a meaning: the bits there control the way GEMDOS treats that 
program. (The least-significant bit of that longword Obit 0), when set, means GEMDOS 
need not clear all of RAM when loading that pregram, only the program's declared BSS. 
This makes programs load faster.) 

The next two bits have been assigned meanings relating to alternative RAM. Bit 1, when 
clear, means that the pregram must be loaded into ST RAM; bit 2, when dear, means that 
Malloc calls by that program must be satisfied using ST RAM. 

When one of these bits is set, the corresponding operation (pregram load, MallOC call) may 
be satisfied from "alternative" RAM. In general, alternative is considered preferable to ST 
RAM. If a program doesn't break any of the rules for eligibility in alternative RAM, it is 
desirable to set those bits in its header. 

Bit Meaning 

0 Only dear BSS 

1 Alternative RAM Load 

2 Alternative RAM MallOC 

If TT RAM is eligible to satisfy a request, but there isn't enough of it available, the request 
will come from ST RAM. If there isn't enough of that, the request fails. 

For loading programs, "enough" RAM is a relative thing. For one program, it's more 
important to run fast than it is to have a lot of memory, so "enou^" RAM is, say, 256K 
more than its own declared requirements (text+data+bss). For another, having lots of 
RAM is more important, even if it means not running as fast as possible. 

A new field in the pregram's header, called the TPAsize field, reflects the memory 
requirements of the program. If the program's "program-load" bit is dear (meaning it 
must load in ST RAM) this field is ignored, and the program is loaded into ST RAM. If the 
program can be loaded in alternative RAM, and there's more alternative RAM than ST 
RAM, the fidd is ignored and the program is loaded into alternative RAM. The field is 
only checked if alternative RAM is eligible for loading the program, and there is more ST 
RAM available. In that case, the TPAsize field tells how much alternative RAM is "enough." 
If there is "enough" alternative RAM, the program loads there; if not, the program loads in 
ST RAM. 
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The TPAsize field tells, in 128K steps, how much alternative RAM is enough. The amount 
is added to the declared size (text+data+bss) of the prc^ram. If there is less than this 
amount available, the pregram gets loaded into ST RAM. The field is four bits wide, and 
is in the high four bits of the prcgram-flags longword. The amount is the field's value 
times 128K, plus 128K. Therefore a value of zero, which is what aU programs have 
currently, means 128K. The value can go up to 15, meaning 2MB. 


Example 


Setup: A program's altemative-RAM load bit is set. Its TPAsize field is set for 512K. 

Its text+data+bss size is 11 OK. 

Result: If there is more alternative RAM than ST RAM, the program loads into 

alternative RAM. 

If there is more ST RAM, the TPAsize field is taken into account. If there is 
622K of alternative RAM available, or more, the program loads into 
alternative RAM. If not, it loads into ST RAM. 


In this example, it's possible that there isn't 622K of ST RAM available either. If there is 
more than IlOK, though, the pregram will still be loaded and run; the TPAsize field is not 
considered an absolute minimum for the program to load. 11 OK is the prcgiam's declared 
text+data+bss size: that, plus space for a small initial stack, is the absolute minitnnm 

Remen±)er, TPAsize does net reflect the maximum or minimum size cf the TPA the 
pregram will ultimately get. It's just the tiebreaker in the case where there is more ST 
RAM than alternative RAM, and GEMDOS has to know where to put the program. 


What Does It All Mean? 


There are two common memory models for programs on the Atari ST. One has the user 
or library declare a "stack size" at compile time or link time. The runtime startup moves 
the stack painter to the end of the pregram plus the stack size and uses Mshrink to give the 
rest of the TPA back to GEMDOS. Then, as the program calls the library mallOcQ, it uses 
Malloc to get memory back from the OS. For this kind of pre^ram, the TPAsize field should 
represent at least as much space as the "stack size" the startup will use. MWC, GCC, 

Turbo C, and lots of other environments use this memory model. 
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The other memoiy model keeps some amount of memoiy, and that memoiy is used as a 
"heap" - the stack grows down from the top of it, and library mallOCO calls use memory up 
from the bottom. For this kind of prc^m, the TPAsize field should be the fninimnm 
reasonable size of the stack+heap space. Alcyon C uses this memory model. 

You may wonder why these fields are part of the program header, and not controlled by, 
say, new GEMDOS calls, or new parameters to Pexec. The reason is that they are properly 
part of the pregram: a program's altemative-RAM characteristics and memory requirements 
are inherent in its behavior. They're not based on its parent's behavior, and its parent 
should ncx have to know about them in order for GEMDOS to make intel ligent decisions. 

Since the information is in the program's header, it can be changed by an outside utUiity 
without special knowledge of ±e pregram's structure. If you can see that a program 
doesn't do screen-flipping or talk to the DMA chip directly, it can probably be run in 
alternative RAM, and you could set its flags appropriately. 


After Your Program Loads 

The bit in the pregram header which controls the eligibility of alternative RAM for MallOC 
calls is intended for compatibility, so existing programs which have no knowledge of 
alternative RAM can get the benefit of the higher speed and extra capacity. 

New pregrams, written after the publication of this information, can use a new call, 
MxallOCQ. This call works like MallOcQ, but takes an extra parameter: a flag t-H1in g where to 
get the memory. 

Mode Meaning 

0 ST RAM only 

1 alternative RAM only 

2 either, ST RAM preferred 

3 either, alternative RAM preferred 

If amount is -IL, the size of the largest single block of the type specified by mode is 
returned. In that case, mode values 2 and 3 are identical, and the size of the largest block 
of either type is returned. 

If amount is not -IL, and a block of that size is available in the typeCs) of memory specified 
by mode, the block is allocated and its starting address is returned. 

It should be dear that the MallocQ call devolves into a MxallOcO call with a mode value of 0 
or 3, depending on the state of the Malloc-eligibility bit in the pregram's header. 
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other Important Notes 


The Line-A graphics interface is maintained for backward compatibility with 
existing ST programs only. It should not be used for new programs. It will 
not keep pace with future hardware or software improvements. The VDI 
should be used. 


Serial Port: There are some known problems in the serial port code of the TT and 
MEGA STe: 

- Using the SCC ports with anything but 8 bits, no parity doesn't work. 

- You can't set the flow centred mode to artything but "none." 

- lorec(0) always provides the lorec information of the ST MFP. 

Both of these are fixed by the AUTO-folder patch program SERPTCH1.PRG. 


Page 32 


Atari TT 030 TOS Release Notes - 6 S^tember 1991 



